<style type="text/css">
    .productNote {
        font-style: italic;
        font-size: smaller;
    }
</style>
<h1 align="center">ZoneLayout Manual</h1>
<hr/>

<h1>Contents</h1>

<p>
<ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#theBasics">The Basics</a></li>
    <ul>
        <li><a href="#simpleExample">A Simple Example</a></li>
    </ul>
    <li><a href="#theApi">The API</a></li>
    <ul>
        <li><a href="#layoutLanguage">The Layout Language</a></li>
        <ul>
            <li><a href="#zones">Zones</a></li>
            <li><a href="#modifiers">Modifiers</a></li>
            <li><a href="#presetComponents">Preset Components</a></li>
        </ul>
        <li><a href="#binding">Binding</a></li>
        <li><a href="#templates">Templates</a></li>
        <li><a href="#optimization">Optimization</a></li>
    </ul>
    <li><a href="#theEngine">The Engine</a></li>
    <ul>
        <li><a href="#engineBasics">Engine Basics</a></li>
        <li><a href="#preferredSize">Preferred Size</a></li>
        <li><a href="#resizing">Resizing: Give and Take</a></li>
    </ul>
</ul>
</p>

<a name="introduction">
<h1>Introduction</h1>
</a>

<p>
    Arranging items in a window
    has traditionally been a tedious and cumbersome task. Layout
    APIs have given programmers precise control over layouts but leave them
    with fragile and confusing code. Visual design tools give the
    programmer an approximate view of the end result but tie the programmer
    to the tool and suffer from code mangling, binary formats, forced
    context switching, and static results.
</p>

<p>
    ZoneLayout provides the programmer with the best of both
    worlds: a simple yet powerful API and a pseudo-visual representation of
    the final result all without leaving the source code.
</p>

<p>
    This guide is an introduction to the ZoneLayout system.
    Currently the only implementation is for Java Swing, but
    implementations for SWT, Windows Forms, wxWidgets, and HTML/CSS may be
    forthcoming based on demand. If you're a Swing programmer,
    read on to learn how ZoneLayout can greatly simplify the layout process
    for you. If you work with another GUI toolkit, you can still
    learn about the general principles of the ZoneLayout system.
</p>

<a name="theBasics">
<h1>The Basics</h1>
</a>

<p>
    ZoneLayout is, at its core, still a grid-based layout like
    GridBagLayout, JGoodies FormLayout, etc. The display area is
    divided into a virtual grid and individual cells are expanded and
    contracted based on the space requirements of the individual components
    and parameters in the layout definition. The layout engine in
    ZoneLayout is a custom implementation, but if you've worked with any of the other
    grid-based systems before, the behavior will be very familiar.
</p>

<p>
    What makes ZoneLayout unique is the API and the manner in which a
    programmer defines a layout, specifically a
    2-dimensional regular-expression-like language that utilizes the
    virtual grid that is inherent to fixed-width fonts used by most
    editors. A programmer uses this language to define zones,
    properties of zones, and then binds components into the zones.
    All this jargon makes it sound complicated, but it's actually incredibly
    simple and intuitive. Here's a simple example.
</p>

<a name="simpleExample">
<h2>A Simple Example</h2>
</a>

<div class="code">
    ZoneLayout layout = ZoneLayoutFactory.newZoneLayout();
    layout.addRow("a&gt;b-");
    layout.addRow(".a~b");

    JPanel basePanel = new JPanel(layout);
    basePanel.add(new JLabel("Name:"), "a");
    basePanel.add(new JTextField(20), "b");
</div>

<p>
    This results in the following (assuming there's some
    JFrame bootstrapping code):
</p>

<div align="center">
    <img alt="Simple Example Window" src="images/simpleExample.png"/>
</div>

<p>
    There are two important parts to the code: the layout definition and the binding. The layout definition
    lies within the two <code>layout.addRow(...)</code> method calls and looks like:
</p>

<div align="center">
    <img alt="Simple Example Layout Definition" src="images/simpleExampleLayoutDefinition.png"/>
</div>

<p>
    ZoneLayout will create a zone the first time an alphabetical character
    is encountered and extend the zone when it sees that character again (It scans from left to right, top to bottom). The
    two characters act as the upper left and lower right corners of the zone.
    So this layout definition creates two zones '<code>a</code>' (colored green) and '<code>b</code>' (colored yellow):
</p>

<div align="center">
    <img alt="Simple Example Layout Definition With Zones Colored"
         src="images/simpleExampleLayoutDefinitionColored.png"/>
</div>

<p>
    Any other characters that lie within a zone's boundary modify the zone (except the '<code>.</code>' character
    which is just a spacer character to maintain the grid). In the above definition:
    <ul>
        <li>The '<code>&gt;</code>' character tells ZoneLayout to align anything in zone '<code>a</code>' to the right.
        </li>
        <li>The '<code>-</code>' character tells ZoneLayout to horizontally fill zone '<code>b</code>' with whatever is
            inside of it.</li>
        <li>The '<code>~</code>' character tells ZoneLayout to expand zone '<code>b</code>' horizontally to fill any
            extra space.</li>
    </ul>
</p>

<p>
    Components are bound into zones '<code>a</code>' and '<code>b</code>' by passing in the zone name as the constraint
    in the <code>basePanel.add(...)</code> method calls. So in the simple example, a JLabel is bound to zone
    '<code>a</code>' and a JTextField to zone '<code>b</code>'.
</p>

<p>
    When the ZoneLayout engine runs during our Simple Example, it knows that there is a JLabel in zone '<code>a</code>'
    that needs
    to be aligned to the right, and a JTextField in zone '<code>b</code>' that should horizontally fill its available
    space <em>and</em>
    expand into any more horizontal space that's available. So if we drag to make the window bigger, the JTextField
    gets bigger:
</p>

<div align="center">
    <img alt="Simple Example Expanded" src="images/simpleExampleExpanded.png"/>
</div>

<p>
    Note that the available vertical space is not filled. That's because we didn't tell either zone '<code>a</code>' or
    '<code>b</code>' to expand into the available vertical space.
</p>

<p>
    You should now have a general idea of how the ZoneLayout system works. You can learn a lot more about the
    ZoneLayout system by continuing on. If you're familiar with the other grid-based layout systems mentioned
    earlier, then you can probably just get away with perusing the API documentation here and jumping right in.
</p>

<a name="theApi">
<h1>The API</h1>
</a>

<p>
    There are essentially two parts to the ZoneLayout API: the usual java API and then the custom language used to
    define layouts.
</p>

<p>
    Typically when using ZoneLayout, you should only have to do two things through the java API: (1) instantiate an instance
    of the layout through <code>ZoneLayoutFactory.newZoneLayout()</code> and (2) add rows to the layout through the
    <code>addRow(...)</code> methods, as in our simple example from earlier:
</p>

<div class="code">
    ZoneLayout layout = ZoneLayoutFactory.newZoneLayout();
    layout.addRow("a&gt;b-");
    layout.addRow(".a~b");
</div>

<p>
    There are, however, two instances in the current version where you need to use the java API as opposed to using
    the layout language: if you want to custom tailoring resizing weights ("give" and "take") associated with zones or
    specifying the margins for a zone.
</p>

<a name="layoutLanguage">
    <h2>The Layout Language</h2>
</a>

<p>
    Almost all code editors use a fixed-width font so all of the characters in the editor are on a virtual
    grid. Hence, we can model windows using rectangular groupings of characters. In the ZoneLayout system, you
    use some characters to define zones in your model and then other characters to modify the behavior of those zones.
</p>

<a name="zones">
<h3>Zones</h3>
</a>

<p>
    <span class="important">You create a zone with an alphabetical character
    (as defined by java.lang.Character.isLetter()).</span>
    So, the simplest layout can be specified as:
</p>

<div class="code">
    layout.addRow("w");
</div>

<div align="center">
    <img alt="Zone 'w'" src="images/zoneW.png"/>
</div>

<p>
    This creates a layout with a single zone '<code>w</code>'. <span class="important">Note that a zone object is
    created during a call to <code>addRow(...)</code> so you can modify the object right afterwards using
    <code>layout.getZone("w")</code> if you want to.</span>  But be careful when doing so.  <span class="important">
    The layout code is not compiled until a component is added to the panel or you explicitly call
    <code>layout.compile()</code>.</span>  So if you modify the same
    property of a zone in the layout language and through the java API, the layout language modifier will
    override the setting you made through the java API when <code>layout.compile()</code> is called.
</p>

<p>
    <span class="important">You can extend a zone by using the spacer character '<code>.</code>' and reusing the same
    character you used to create the zone initially to mark the lower right corner.  Always define zones starting with
    the top left corner.</span> So, if you want to make
    zone 'w' "bigger" (bigger is relative, see the section on <a href="#optimization">layout optimization</a> for
    details), you could just do:
</p>

<div class="code">
    layout.addRow("w.....");
    layout.addRow(".....w");
</div>

<div align="center">
    <img alt="Zone 'w' Made Bigger" src="images/zoneWBigger.png"/>
</div>

<p>
    Zone 'w' now stretches across 5 characters in width and 2 characters in height. If you want to create other zones,
    you just add other characters, like so:
</p>

<div class="code">
    layout.addRow("bfa..a");
    layout.addRow("w.....");
    layout.addRow(".....w");
    layout.addRow("s....s");
</div>

<div align="center">
    <img alt="Browser Layout With 'w' Filling" src="images/browserLayout.png"/>
</div>

<p>
    The layout now represents the beginnings of a very simple browser (<b>b</b>ack button, <b>f</b>orward button,
    <b>a</b>ddress bar, <b>w</b>eb page, <b>s</b>tatus bar).
    (The zones are colored in the figure to show you where they apply.)
</p>

<a name="modifiers">
<h3>Modifiers</h3>
</a>

<p>
    <span class="important">You can modify the behavior of a zone by placing a modifier character within a zone's
    boundaries.  You can use more than one modifier</span>. Continuing with
    the example from the last section, zone '<code>w</code>' is going to contain a web page viewer which needs to take
    up all of the available space. So, zone '<code>w</code>' needs to fill in both directions, hence the use of the
    '<code>+</code>' modifier.
</p>

<div class="code">
    layout.addRow("bfa..a");
    layout.addRow("w+....");
    layout.addRow(".....w");
    layout.addRow("s....s");
</div>


<div align="center">
    <img alt="Browser Layout" src="images/browserLayoutFillW.png"/>
</div>

<p>
    All of the currently available modifiers are listed in the table below.  <span class="important">Note that each
    modifier provides some visual indication of its behavior so they are easy to remember ('<code>&gt;</code>' means
    align right, '<code>!</code>'
    means expand vertically, etc.).</span>  The image on the right side shows how layout behavior is
    changed by the modifier.  The white square is the display area, the green square is the zone, and the red square is
    the component in the zone.  <span class="important">A component is centered in a zone by default.</span>

</p>

<div align="center">
    <table cellpadding="0" cellspacing="0">
        <tr>
            <th>Modifier Character</th>
            <th colspan="2">Behavior</th>
        </tr>
        <script type="text/javaScript">
            var modifiers = new Array();
            modifiers.push(new Array('<', 'Align zone component to the left', 'images/modifierLeft.png'));
            modifiers.push(new Array('>', 'Align zone component to the right', 'images/modifierRight.png'));
            modifiers.push(new Array('^', 'Align zone component to the top', 'images/modifierTop.png'));
            modifiers.push(new Array('_', '(underscore) Align zone component to the bottom', 'images/modifierBottom.png'));
            modifiers.push(new Array('-', '(dash) Make the zone component fill the zone horizontally', 'images/modifierFillHorizontally.png'));
            modifiers.push(new Array('|', 'Make the zone component fill the zone vertically', 'images/modifierFillVertically.png'));
            modifiers.push(new Array('+', 'Make the zone component fill the zone horizontally and vertically', 'images/modifierFillBoth.png'));
            modifiers.push(new Array('~', 'Expand the zone horizontally into available space (sets the horizontal "take" of the zone to 1)', 'images/modifierExpandHorizontally.png'));
            modifiers.push(new Array('!', 'Expand the zone vertically into available space (sets the vertical "take" of the zone to 1)', 'images/modifierExpandVertically.png'));
            modifiers.push(new Array('*', 'Expand the zone horizontally and vertically into available space (sets the horizontal and vertical "take" of the zone to 1)', 'images/modifierExpandBoth.png'));

            for (i = 0; i < modifiers.length; i++) {
                document.write('<tr>');
                i % 2 == 0 ? document.write('<td align="center">') : document.write('<td bgcolor="#EEEEEE" align="center">');
                document.write('<font size="+3"><code>')
                document.write(modifiers[i][0]);
                document.write('</code></font>')
                document.write('</td>');
                i % 2 == 0 ? document.write('<td>') : document.write('<td bgcolor="#EEEEEE">');
                document.write(modifiers[i][1]);
                document.write('</td>');
                i % 2 == 0 ? document.write('<td>') : document.write('<td bgcolor="#EEEEEE">');
                document.write('<img src="' + modifiers[i][2] + '"/>');
                document.write('</td>');
                document.write('</tr>');
            }
        </script>
    </table>
</div>

<p>
    Continuing with our example:
    <ul>
        <li>The address bar needs to expand horizontally into available space and fill that space.</li>
        <li>The web page also needs to expand into available space both horizontally and vertically in addition to filling it.</li>
        <li>The status bar should align to the left.</li>
    </ul>
    So the code now looks like:
</p>

<div class="code">
    layout.addRow("bfa-~a");
    layout.addRow("w+*...");
    layout.addRow(".....w");
    layout.addRow("s&lt;...s");
</div>

<div align="center">
    <img alt="Complete Browser Layout" src="images/browserLayoutComplete.png"/>
</div>

<a name="presetComponents">
<h3>Preset Components</h3>
</a>

<p>
    Layouts often involve extensive use of spacer components to pleasantly separate components on the display.
    Instead of forcing you to create spacer zones, ZoneLayout has a few shortcuts for a number of useful spacer
    components.  These preset components are accessed through the numerical digits <code>0-9</code> and the
    '<code>~</code>', '<code>!</code>', and '<code>*</code>' characters in a layout.
</p>

<p>
    By default, ZoneLayout has the following component presets:
</p>

<div align="center">
    <table cellpadding="4" cellspacing="0">
        <tr>
            <th>Preset Character</th>
            <th colspan="2">Behavior</th>
        </tr>
        <script type="text/javaScript">
            var presets = new Array();
            presets.push(new Array('1', '3 pixel horizontal spacer'));
            presets.push(new Array('2', '6 pixel horizontal spacer'));
            presets.push(new Array('3', '12 pixel horizontal spacer'));
            presets.push(new Array('4', '18 pixel horizontal spacer'));
            presets.push(new Array('5', '3 pixel vertical spacer'));
            presets.push(new Array('6', '6 pixel vertical spacer'));
            presets.push(new Array('7', '12 pixel vertical spacer'));
            presets.push(new Array('8', '18 pixel vertical spacer'));
            presets.push(new Array('~', 'Horizontal expander with a "take" of 1'));
            presets.push(new Array('!', 'Vertical expander with a "take" of 1'));
            presets.push(new Array('*', 'Horizontal and Vertical expander with a "take" of 1'));

            for (i = 0; i < presets.length; i++) {
                document.write('<tr>');
                i % 2 == 0 ? document.write('<td align="center">') : document.write('<td bgcolor="#EEEEEE" align="center">');
                document.write('<font size="+2"><code>')
                document.write(presets[i][0]);
                document.write('</code></font>')
                document.write('</td>');
                i % 2 == 0 ? document.write('<td>') : document.write('<td bgcolor="#EEEEEE">');
                document.write(presets[i][1]);
                document.write('</td>');
                document.write('</tr>');
            }
        </script>
    </table>
</div>

<p>
    <span class="important">To use a preset, just use its corresponding character <em>outside</em> of a zone.</span>
    Here's an example of a small dialog:
</p>

<div class="code">
    ZoneLayout layout = ZoneLayoutFactory.newZoneLayout();
    layout.addRow("a&gt;a2b-~b");
    layout.addRow("...6....");
    layout.addRow("c&gt;c2d-~d");
    layout.addRow("...7....");
    layout.addRow("e......e");

    JPanel basePanel = new JPanel(layout);
    basePanel.add(new JLabel("First Name:"), "a");
    basePanel.add(new JTextField(20), "b");
    basePanel.add(new JLabel("Last Name:"), "c");
    basePanel.add(new JTextField(20), "d");
    basePanel.add(new JButton("OK"), "e");
</div>

<div align="center">
    <img alt="Preset Window" src="images/presetLayout.png"/>
</div>

<p>
    The preset '<code>2</code>' is converted into a 6 pixel invisible horizontal boundary in between zones '<code>a</code>'
    and '<code>b</code>', and zones '<code>c</code>' and '<code>d</code>'.  The preset '<code>6</code>' is converted
    into a 6 pixel invisible vertical boundary between the first and third rows.  The preset '<code>7</code>' is
    converted into a 12 pixel invisible boundary between the third and last rows.  <span class="important">As a simple
    reminder to where the vertical spacer's begin in the presets, just remember "High 5"</span>.  Here's what the
    window looks like:
</p>

<div align="center">
    <img alt="Preset Window" src="images/presetWindow.png"/>
</div>

<p>
    The presets are configurable.  You can specify a preset by using the
    <code>setComponentPreset(...)</code> method on the layout and passing in
    a preset id from <code>0 - 9</code> and a Preset object created using the static factory methods
    on the Preset class (<code>createSpacer(...)</code>, <code>createFlexibleSpacer</code>, and
    <code>createExpander(...)</code>).
</p>

<p>
    The Java Look and Feel Design Guidelines generally call for 6 pixel gaps between related components (except in
    toolbars where the gap should be 3 pixels between related buttons) and gaps that are multiples of 6 pixels
    everywhere else.  So presets <code>2</code> and <code>6</code> should be the presets you use the most.
</p>

<a name="binding">
<h2>Binding</h2>
</a>

<p>
    Binding is simply telling ZoneLayout what component you want in a particular zone. This is accomplished by passing
    in the name of zone as the constraint when you add that component to a panel.
</p>

<p>
    The necessary components for the final simple browser layout from earlier would be bound like so:
</p>

<div class="code">
    JPanel basePanel = new JPanel(layout);
    basePanel.add(new JButton("Back"), "b");
    basePanel.add(new JButton("Forward"), "f");
    basePanel.add(new JTextField(20), "a");
    JScrollPane jsp = new JScrollPane(new JTextPane());
    jsp.setPreferredSize(new Dimension(400, 200));
    basePanel.add(jsp, "w");
    basePanel.add(new JLabel("status"), "s");
</div>

<p>
    This results in the following window (assuming simple JFrame bootstrapping):
</p>

<div align="center">
    <img alt="Complete Browser Layout" src="images/browserWindow.png"/>
</div>

<p>
    And this is what it looks like after resizing:
</p>

<div align="center">
    <img alt="Complete Browser Layout" src="images/browserWindowResized.png"/>
</div>

<a name="templates">
<h2>Templates</h2>
</a>

<p>
    Often when creating layouts, programmers find themselves having to duplicate the same code for a number of rows
    and columns or having to place layout code within loops.  This spreads the layout code out even more and makes it more
    difficult to understand exactly what is going on.
</p>

<p>
    ZoneLayout enables the programmer to avoid this problem by providing a simple template methodology.  Within a
    layout definition, you can define rows as being part of a template and then insert those rows dynamically.
    <span class="important">(In the current version this functionality is only available for rows, not columns.)</span>
</p>

<p>
    To create a template, you just provide a second argument to the <code>addRow(...)</code> method call that specifies
    the name of the template.  If you want to add more rows to the same template, then use the same name again.
</p>

<p>
    Here is an example layout that you might use when building an editor for <code>java.util.Map</code> values:
</p>

<div class="code">
    ZoneLayout layout = ZoneLayoutFactory.newZoneLayout();
    layout.addRow("h......h");
    layout.addRow("...6....");
    layout.addRow("k&gt;k2v-~v", "mapEntry");
    layout.addRow("...6....", "mapEntry");
</div>

<div align="center">
    <img alt="Template Layout" src="images/templateLayout.png"/>
</div>

<p>
    The first two rows are part of the basic layout and then the last two are contained in the '<code>mapEntry</code>'
    template.  <span class="important">Rows contained in a template are removed from the layout prior to the layout's
    use.</span>  So the base layout actually looks like:
</p>

<div align="center">
    <img alt="Template Layout Base" src="images/templateLayoutBase.png"/>
</div>

<p> Before binding a component to a zone in a template, you'll need to insert the template first.
    Here's the code that uses this layout:
</p>

<div class="code">
    Map myMap = new HashMap();
    myMap.put("Product", "ZoneLayout");
    myMap.put("Version", "1.0");
    myMap.put("Vendor", "Attic Labs LLC");

    JPanel basePanel = new JPanel(layout);
    basePanel.add(new JLabel("Map Values"), "h");

    for (Iterator iterator = myMap.keySet().iterator(); iterator.hasNext();) {
        String key = (String) iterator.next();

        <b>layout.insertTemplate("mapEntry");</b>

        basePanel.add(new JLabel(key + ":"), "k");
        basePanel.add(new JTextField((String) myMap.get(key)), "v");
    }
</div>

<p>
    Note the call to <code>layout.insertTemplate("mapEntry")</code> prior to binding components to zones '<code>k</code>'
    and '<code>v</code>'.  Also note that you can just refer to the zones '<code>k</code>' and '<code>v</code>' without
    specifying that you are referring to the zones in the template you just inserted.  <span class="important">Every time
    you insert a template, the zone names are reset to point to the latest instance of the template.</span>  This code
    will result in the following layout since there are 3 entries in the Map:
</p>

<div align="center">
    <img alt="Template Layout After Insertion" src="images/templateLayoutAfterInsertion.png"/>
</div>

<p>
    And the final window will look like this:
</p>

<div align="center">
    <img alt="Map Viewer Window" src="images/templateWindow.png"/>
</div>

<p>
    You can have multiple templates within a layout, but be careful when putting two or more templates back-to-back.
    <span class="important">When back-to-back templates are removed from a layout, they are assigned the same insertion
    point by ZoneLayout and, hence, their initial ordering is not maintained.</span>
</p>

<p>
    <span class="important">Zones must be wholly contained within templates or span them.</span>  You cannot have a
    zone start outside of template and finish inside one or vice versa.
</p>

<a name="optimization">
    <h2>Optimization</h2>
</a>

<p>
    You may have noticed in the simple browser example layout from the <a href="#layoutLanguage">Layout Language Section</a>
    that there was an extra row in the layout that wasn't needed.  That row is bolded here:
</p>

<div class="code">
    layout.addRow("bfa-~a");
    layout.addRow("w+*...");
    <b>layout.addRow(".....w");</b>
    layout.addRow("s&lt;...s");
</div>

<p>
    That row could have been deleted and zone '<code>w</code>' placed all on one row like so:
</p>

<div class="code">
    layout.addRow("bfa-~a");
    layout.addRow("w+*..w");
    layout.addRow("s&lt;...s");
</div>

<p>
    Is the second one better?  Trivially.  As was mentioned previously, ZoneLayout is a grid-based layout so
    you may be wondering if deleting one row from the layout makes it more efficient.  It doesn't really matter.
    <span class="important">Internally, ZoneLayout optimizes the layouts you create and pans down the layout
    to the minimum number of rows and columns necessary to achieve the same result.</span>  So technically, those
    two layouts are equivalent.  They both result in the same 3 column and 3 row layout internally:
</p>

<div align="center">
    <img alt="Optimized Browser Layout" src="images/browserLayoutOptimized.png"/>
</div>

<p>
    So when you're creating your layouts, don't be concerned with the size of the layout.  Yes, optimizing a larger
    layout takes additional time, but it's trivial.  Your time and the clarity of the layout are <em>much</em> more
    valuable.
</p>

<a name="theEngine">
<h1>The Engine</h1>
</a>

<p>
    The engine positions and sizes the bound components in the display space based on the definitions provided
    by the layout.  Although the internal operations of the engine aren't particularly pertinent to using ZoneLayout, it's
    important to understand the sizing behavior of the engine and how it affects your layouts.
</p>

<a name="engineBasics">
<h2>Engine Basics</h2>
</a>

<p>
    <span class="important">All calculations within the engine start with the preferred size of the layout and then
    proceed from there.</span>  If
    there's more space available than needed to fit the preferred size requirements, then the engine allocates additional
    space based on the "take" of the zones.  If there's less space than needed, then the engine works downwards
    from the preferred size to the minimum size based on the "give" of the zones.
</p>

<div align="center">
    <img alt="Weighted Sizing" src="images/weightedSizing.png"/>
</div>

<p>
    <span class="important">Although ZoneLayout is a grid-based layout system, internally the engine operates on rows
    and columns.</span>  So after your layout is <a href="#optimization">optimized</a>, the engine then breaks it
    down into rows and columns and sizes the individual rows and columns based on the components contained within.
</p>

<a name="preferredSize">
<h2>Preferred Size</h2>
</a>

<p>
    All calculations start from the preferred size of the layout.  The preferred size is calculated in two passes.  In
    the first pass, only zones that are wholly contained within one row or column are considered.  In the second pass,
     zones that span more than one row or column are considered.
</p>

<p>
    The first pass is used to initially size rows and columns based on components that are wholly contained within
    each row and column.  The second pass then enlarges rows and columns to make sure that zones that span multiple
    rows or columns have their requested preferred size.  <span class="important">This ensures that all components
    in the layout will have their preferred size.</span>
</p>

<p>
    Note that during the second pass, when choosing which columns or rows to enlarge for a zone that needs more space,
    ZoneLayout takes into account the "take" of the rows or columns.  If it can't find any column with a "take" greater
    than zero, it will then evenly distribute the needed space among all of the rows or columns that the zone spans.
</p>

<a name="resizing">
<h2>Resizing: Give and Take</h2>
</a>

<p>
    Instead of one monolithic resize "weight" like other layout managers, ZoneLayout allows you to set two
    "weights" for zones: "give" and "take".  The "give" of a zone is taken into account when the space available
    for a layout is less than the preferred space.  The "take" of a zone is taken into account when the space
    available is greater than the preferred space of the layout.  Think of them as greediness factors.  When there's
    more space available, how much will a zone "take"?  When there's less space available, how much is a zone willing
    to "give"?
</p>

<p>
    <span class="important">Both of these values are <code>int</code>'s and they are relative to the total of all
    the "weights" within the layout.</span> Say there's a zone with a "take" of 7 and another with a "take" of 3,
    giving a total "take" of 10 in the layout.  That means that one zone will always get 7/10's of the available extra
    pixels and another one with always get 3/10's.
</p>

<div align="center">
    <img alt="Take Diagram" src="images/takeDiagram.png"/>
</div>


<p>
    <span class="important">By default, the "take" of a zone is zero and the "give" is equal to its size after
    optimization.  So, the default behavior of a zone is to not expand into extra available space,
    but shrink to the minimum size if necessary.</span>  For example, looking at the optimized structure of the
    simple browser layout from earlier in the manual:
</p>

<div align="center">
    <img alt="Take Diagram" src="images/browserLayoutOptimized.png"/>
</div>

<p>
    In this layout, the default "takes" of all of the zones would be 0 in both directions; zones '<code>b</code>',
    '<code>f</code>', and '<code>a</code>' would have default "gives" of 1 in both directions, and zones '<code>w</code>'
    and '<code>s</code>' would have default "gives" of 1 on the vertical axis, and <em>3</em> on the horizontal
    axis like so:
</p>

<div align="center">
    <img alt="Take Diagram" src="images/browserDefaultVerticalGives.png"/>
    <img alt="Take Diagram" src="images/browserDefaultHorizontalGives.png"/>
</div>

<p>
    "Weights" of zones that span multiple rows or columns are handled specially, similarly to how they are handled
    when calculating the preferred size of a layout.  ZoneLayout will ensure that the "take" or "give" of a zone
    that spans multiple rows or columns is met (i.e. total "take" &gt;= required or total "give" &lt;= required).  If it is
    not, then ZoneLayout will proportionally increase or decrease the "weight" in order to meet the needs of the
    spanning zone.
</p>

<p>
    For example, take the full simple web browser layout from the API section of the manual:
</p>

<div class="code">
    layout.addRow("bfa-~a");
    layout.addRow("w+*...");
    layout.addRow(".....w");
    layout.addRow("s&lt;...s");
</div>


<div align="center">
    <img alt="Take Diagram" src="images/spanningWeightsDiagram.png"/>
</div>

<p>
    You'll notice that zone '<code>w</code>' spans the entire width of the layout and has it's horizontal "take" set
    to 1 by the use of the '<code>*</code>' modifier.  ZoneLayout recognizes that zone '<code>a</code>' already has
    a horizontal "take" of 1 and doesn't need to do anything to meet zone '<code>w</code>'s requirements.
</p>


<p>
    For arguments sake, what happens if the "takes" of zones '<code>f</code>',
    '<code>a</code>', and '<code>w</code>' are explicity set to be 1, 4, and 10 respectively?
</p>

<div align="center">
    <img alt="Take Diagram" src="images/spanningWeightsDiagramWithDistribute.png"/>
</div>

<p>
    Notice that the "takes" of columns are proportionally increased from 0, 1, and 4 to 0, 2, and 8 in order to meet
    the requirement of 10 made by the spanning zone '<code>w</code>'.
</p>

<p>
    It's rare that you'll have to worry about this internal behavior.  Specifying "weights" using the '<code>*</code>',
    '<code>~</code>', and '<code>!</code>' modifiers should suffice for the majority of layouts.
</p>
